How to Make a Quarto Website
First, due credit where credit is due. The following document was heavily influenced by tutorials found on the Quarto website.
Pre-Game
First, I recommend making sure you have a current version of R, RStudio, and Quarto.
Quarto and RStudio have been created by Posit. Quarto is essentially an updated version of RMarkdown files that have some different capabilites than it’s predecessor. I would highly recommend looking ito it. Posit has mad numerous tutorials about the framework. It’s pretty cool.
Getting Started
Create a New Project
Starting to create a webiste is pretty easy. You simple have to create a new project in RStudio.
- Click on the new project button in the top left of the RStudio IDE.
- Select new project
- Select the “Quarto Website” option
- Create a new name for the directory. I host my website on GitHub Pages and follow the naming convention for that (i.e. kpdubose-website which is related to kpdubose.github.io)
- Then click create project. This will create a new project with four files: _quarto.yml, about.qmd, index.qmd, and styles.css.
What are thoose?! (They’re my new files)
Let’s dive briefly into the new files you can see.
quarto.yml
This file is like the yml header that is on most .qmd files. But, this applies to the whole website. It sets the default theme for the whole website by setting headers and footnotes, and references the styles.css, which I will go into a little later.
You can change the theme from page to page (kind of like I did with this page on my website) by specifying a different theme on the individual pages.
about.qmd
This is one of the pages on the website. Pretty basic.
index.qmd
This is the home page. I don’t know what else to say here.
styles.css
This is the styles.css page. You can use it to edit the website theme by specifying specific colors, specific fonts, background colors, etc… I edit this as needed, but most of the Quarto website themes. If you have questions about what a specific theme looks like, they can all be found here.
Let’s check it out
There are two important terminal commands to know.
The first is quarto preview. This is the general, let’s make sure everything is linked properly and working the way I was hoping it would.
The second command is quarto render. This command builds the website. It should be run before you upload the files to the cloud, or if you make any big changes to the themes of the website.
When you run the quarto preview command it should look something like this (assuming you haven’t made any changes).
But yeah. That’s the basics. You can play around with it. The next few sections cover my ramblings and different work arounds that I have found for problems that I have had. These can all be found by searching the internet, but I thought it might be helpful to keep some here.
Additional Thoughts and Examples
Different Quarto Formats
I’ve started to experiment with a few different formats for pages. The following formats either play nice or they don’t. Specifically, I couldn’t upload the rendered website to GitHub even though quarto preview gave me all kinds of false hope.
Renders with no trouble:
- html
Hurts me time and time again:
- revealjs
Hosting on GitHub pages
The docs folder
If you plan to host on GitHub pages, there are a few tips.
In the _quarto.yml file, include the following:
#| code-copy: true
---
project:
type: website
output-dir: docs
---
I push my entire project including all of my .qmd files and images I used in making my website. When you quarto render it creates a few different files, including an important one called “docs”.
This is the full webiste in a folder. When you push to GitHub, there is an option to build from a specific branch and folder. Make sure you are building from the docs folder.
.nojekyll file
If you’re hosting on GitHub, you need to include a .nojekyll file.
You can include one by running the following line of cod in the command terminal
For Windows:
copy NUL .nojekyll
For Mac/Linux:
touch .nojekyll
The final push
In the command terminal, the following lines of code can be run to push to GitHub. This is after you’ve linked the depository to you project.
quarto render
git add docs
git commit -m "Publish site to docs/"
git push
How to structure a _quarto.yml
Below is the code I have used for my _quarto.yml. This has a brief explanation of each code chunk and what it does for the website.
This section defines the project type, and the output-directory. Since I host my website on GitHub, I have my output-directory set as docs, as explained above. The render option let’s you select which documents you would like to render to the website. “*.qmd” tells Quarto to render all .qmd files. “!tournament-announcements/” and “!resumes/” tells Quarto to not render any files found in this directory
project:
type: website
output-dir: docs
render:
- "*.qmd"
- "!tournament-announcements/"
- "!resumes/"
The next two section deal with the look of the website. This specific section defines the title of the website as “Kline DuBose” (fitting for a portfolio website) and then establishes the navbar at the top of the page. It sets it to the left and makes then links to pages I have made and set in the navbar. There are a lot of options for this, but googling website options makes it easy for you to look into it.
website:
title: "Kline DuBose"
navbar:
left:
- href: index.qmd
text: Home
- href: main_about.qmd
text: About
- href: main_projects.qmd
text: Projects
This section sets up the footer for the entire website. Mine includes links with specific icons and different websites. As well as the address of my institution.
page-footer:
background: light
left:
- icon: twitter-x
href: https://x.com/KlineDuBose
- icon: github
href: https://github.com/KPDuBose
- icon: linkedin
href: https://www.linkedin.com/in/kline-dubose/
- icon: envelope
href: mailto:kline.dubose@utah.edu
right:
- "295 Chipeta Way, 3rd Floor
Salt Lake City, UT 84108
United States"
This last section sets additional format information for the website.
format:
html:
theme:
- morph
- custom.scss
css: styles.css
toc: true
Resume
You should be able to include your resume or CV on the website without too much trouble. I have a quarto document that I use to make sure it renders nicely and that I don’t make any mistakes with my poor Microsoft Word skills. Just make sure that you include a “.docx” or a ”.pdf” option in the render section of your _quarto.yml file. I haven’t played around with it a ton.
If you would like to see the files I’ve used to construct my CV, they can be found on my GitHub.
That’s it, for now
That should be enough information to help you get started. Quarto is a versatile tool, and they have a lot of tutorials to help one get profecient at using it.
Feel free to check out my GitHub project and let me know if you have any question.
Good luck out there!